.. _example-phreeqc-basics-03:

03 - File as parameter input
============================

The third way to drive a parameterised input, and the one that matters most
in practice: take the values from a file.

:ref:`example-phreeqc-basics-02` sweeps parameters over ranges you choose.
This runs them over values somebody measured -- a sampling campaign, one
simulation per sample.


The data
--------

.. csv-table:: analysis_data.tsv
   :file: analysis_data.tsv
   :header-rows: 1
   :delim: tab

Each row is a water. The columns are the quantities the input needs.


Mapping columns to parameters
-----------------------------

.. raw:: html
   :file: study_ex3.html

The input is parameterised as before. The difference is the study: a
*Discrete Data Study* is pointed at the imported table and each parameter is
mapped to a column, then it runs the input once per row.

The three study types are worth holding together, because choosing between
them is a routine decision:

* **Parametric** -- values you specify, as a range. For exploring behaviour.
* **Discrete data** -- values from a table. For running measurements.
* **Monte Carlo** -- values drawn from distributions. For propagating
  uncertainty.

All three drive the same parameterised input. Only the source of the numbers
differs, which means an input written for one works with the others
unchanged.


The results
-----------

.. figure:: SpeciesConcentrationInput.svg
   :alt: Sodium, potassium and calcium of each sample against simulation number
   :align: center

   What went in: the three cation concentrations against simulation number,
   one point per sample.

   Plot the inputs first on any table-driven study. A wrong unit or a
   misplaced decimal is obvious here and is not obvious three plots later,
   and the model will happily run on either.

.. figure:: SamplesCationView.svg
   :alt: The cation composition of the samples
   :align: center

   The cation composition of the samples, summarising how they differ from
   one another.


Where this goes next
--------------------

The Water Chemistry and Predominance sets both build on this pattern: one
speciates a whole campaign for its saturation indices, the other plots the
samples against a predominance field computed separately.


Source
------

* Parkhurst, D. L. and Appelo, C. A. J. (2013). *Description of input and
  examples for PHREEQC version 3.* U.S. Geological Survey Techniques and
  Methods, book 6, chapter A43.

The sample data is synthetic.